/*
 * @(#)Acl.java	1.16 01/12/12
 *
 * Sun Microsystems, Inc.版权所有版权所有。SUN专有/保密。使用受许可条款的约束。
 */

package java.security.acl;

import java.util.Enumeration;
import java.security.Principal;

/**
 * 表示ACL (Access Control List)的接口。访问控制列表是一种用于保护对资源访问的数据结构。<p>
 *
 * 可以将ACL视为具有多个ACL项的数据结构。接口类型为AclEntry的每个ACL项包含一组与特定主体相关联的权限。
 * (主体代表一个实体，如个人用户或组)。此外，每个ACL条目被指定为正或负。如果为正数，则将权限授予关联主体。
 * 如果为负数，则表示权限都将被拒绝。
 *
 * 每个ACL中的ACL表项遵循以下规则:<p>
 *
 * <ul> <li>每个主体最多可以有一个正ACL表项和一个负ACL表项;即任何主体不允许存在多个正ACL或负ACL表项。
 * 每个条目指定要授予(如果为正)或拒绝(如果为负)的权限集。< p >
 * 
 * <li>如果没有特定主体的条目，则认为该主体具有空(空)权限集。<p>
 *
 * <li>如果存在授予主体特定权限的正面条目，以及拒绝主体相同权限的负面条目，则结果就像从未授予或拒绝该权限一样。< p >
 *
 * <li>个人权限总是覆盖个人所属组的权限。也就是说，个人的消极权限(特定的拒绝权限)覆盖组的积极权限。个人的积极权限覆盖组的消极权限。<p>
 *
 * </ul>
 *
 * <code> java.security.acl </code>包提供了到ACL和相关数据结构(ACL条目、组、权限等)的接口，
 * 而<code> sun.security.acl </code>类提供了接口的默认实现。例如，<code> java.security.acl.Acl </code>
 * 提供到ACL的接口，而<code> sun.security.acl.AclImpl </code>类提供接口的默认实现。
 * 
 * <code> java.security.acl.Acl </code>接口扩展了<code> java.security.acl.Owner </code>接口。
 * Owner接口用于维护每个ACL的所有者列表。只有所有者可以修改ACL。
 * 例如，只有所有者可以调用ACL的<code>addEntry</code>方法向ACL添加一个新的ACL条目。
 * 
 * @see AclEntry
 * @see Owner
 * @see Acl#getPermissions
 * 
 * @version 1.16, 01/12/12
 * @author Satish Dharmaraj 
 */

public interface Acl extends Owner {

    /**
     * Sets the name of this ACL.
     *
     * @param caller the principal invoking this method. It must be an
     * owner of this ACL.
     *
     * @param name the name to be given to this ACL.
     *
     * @exception NotOwnerException if the caller principal
     * is not an owner of this ACL.  
     */
    public void setName(Principal caller, String name)
      throws NotOwnerException;

    /**
     * Returns the name of this ACL. 
     *
     * @return the name of this ACL.
     */
    public String getName();

    /**
     * 向该ACL中添加ACL表项。条目将主体(例如，个人或组)与一组权限关联起来。
     * 每个主体最多可以有一个正ACL表项(指定要授予主体的权限)和一个负ACL表项(指定要拒绝的权限)。
     * 如果ACL中已经存在相同类型的ACL表项(阴性或阳性)，则返回false。
     * 
     * @param caller the principal invoking this method. It must be an
     * owner of this ACL.
     *
     * @param entry the ACL entry to be added to this ACL.
     *
     * @return 成功时为true，如果在此ACL中已经存在同一主体的相同类型(正数或负数)的条目，则为false。
     *
     * @exception NotOwnerException if the caller principal
     *  is not an owner of this ACL.  
     */
    public boolean addEntry(Principal caller, AclEntry entry)
      throws NotOwnerException;

    /**
     * Removes an ACL entry from this ACL.
     * 
     * @param caller the principal invoking this method. It must be an
     * owner of this ACL.
     *  
     * @param entry the ACL entry to be removed from this ACL.
     * 
     * @return true on success, false if the entry is not part of this ACL.
     * 
     * @exception NotOwnerException if the caller principal is not
     * an owner of this Acl.
     */
    public boolean removeEntry(Principal caller, AclEntry entry)
          throws NotOwnerException;

    /**
     * 返回指定主体(表示个人或组等实体)的允许权限集的枚举。该允许的权限集的计算方法如下:<p>
     *
     * <ul>
     *  
     * <li>如果此访问控制列表中没有指定主体的条目，则返回空权限集。<p>
     * 
     * 否则，将确定主体的组权限集。(一个主体可以属于一个或多个组，其中组是主体的一组，由group接口表示。)
     * 组正权限集是主体所属的每个组的所有正权限的并集。组负权限集是主体所属的每个组的所有负权限的并集。
     * 如果某个特定权限同时出现在正权限集和负权限集中，则从这两个权限集中删除该权限。
     *
     * 还确定了单独的正权限集和反权限集。正向权限集包含主体的正向ACL项(如果有)中指定的权限。
     * 类似地，否定权限集包含在否定ACL项(如果有的话)中为主体指定的权限。
     * 如果在此ACL中没有主体的正(负)ACL条目，则认为单个正(或负)权限集为空。<p>
     *
     * 然后使用单个权限总是覆盖组权限的简单规则计算授予主体的权限集。
     * 也就是说，主体的个人否定权限集(特定的拒绝权限)将覆盖组肯定权限集，
     * 并且主体的个人肯定权限集将覆盖组否定权限集。
     * 
     * </ul>
     *
     * @param user the principal whose permission set is to be returned.
     * 
     * @return the permission set specifying the permissions the principal 
     * is allowed. 
     */
    public Enumeration getPermissions(Principal user);

    /**
     * 返回此ACL中条目的枚举。枚举中的每个元素都是AclEntry类型的。
     * 
     * @return an enumeration of the entries in this ACL.
     */
    public Enumeration entries();

    /**
     * 检查指定的主体是否具有指定的权限。如果是，则返回true，否则返回false。
     * 
     * 更具体地说，此方法检查传递的权限是否是指定主体的允许权限集的成员。
     * 允许的权限集由与<code>getPermissions</code>方法使用的算法相同的算法确定。
     * 
     * @param principal the principal, assumed to be a valid authenticated 
     * Principal.
     * 
     * @param permission the permission to be checked for.
     * 
     * @return 主体，假定是一个有效的经过身份验证的主体。
     * 
     * @see #getPermissions
     */
    public boolean checkPermission(Principal principal, Permission permission);

    /**
     * 返回ACL内容的字符串表示形式。
     * 
     * @return a string representation of the ACL contents.
     */
    public String toString();
}
















